Inside Macintosh: Mac OS 8 Toolbox Reference /

Chapter 5 - Menu Manager Reference / Menu Manager Functions

Responding to the User's Choice of a Menu Command /

ContextualMenuSelect

NEW WITH CONTEXTUAL MENUS

Displays a contextual menu.

pascal OSStatus ContextualMenuSelect (MenuHandle inMenuRef,
                     Point inGlobalLocation,
                     Boolean inReserved,
                     UInt32 inHelpType,
                     ConstStr255Param inHelpItemString,
                     const AEDesc* inSelection,
                     UInt32* outUserSelectionType,
                     SInt16* outMenuID,
                     UInt16* outMenuItem);

inMenuRef

On input, a handle to a menu containing application commands to display. The caller creates this menu based on the current context, the mouse location, and the current selection (if it was the target of the mouse). If you pass nil, only system commands will be displayed. The menu should be added to the menu list as a pop-up menu (using the InsertMenu function).

inGlobalLocation

The location (in global coordinates) of the mouse near which the menu is to be displayed.

inReserved

Reserved for future use. Pass false for this parameter.

inHelpType

An identifier specifying the type of help to be provided by the application; see "Contextual Menu Help Type Constants".

inHelpItemString

The string containing the text to be displayed for the help menu item. This string is unused unless you also pass the constant kCMOtherHelp in the inHelpType parameter.

inSelection

On input, a pointer to an object specifier for the current selection. This allows the system to examine the selection and add special system commands accordingly. Passing a value of nil indicates that no selection should be examined, and most likely, no special system actions will be included.

outUserSelectionType

On output, a pointer to a value indicating what the user selected from the contextual menu; see "Contextual Menu Help Type Constants".

outMenuID

On output, a pointer to the menu ID of the chosen item, if outUserSelectionType is set to kCMMenuItemSelected.

outMenuItem

On output, a pointer to the menu item chosen, if outUserSelectionType is set to kCMMenuItemSelected.

function result

A result code; see "Result Codes". The result code userCanceledErr indicates that the user did not select anything from the contextual menu and no further processing is needed; outUserSelectionType will be set to kCMNothingSelected.

DISCUSSION

If the IsShowContextualMenuClick function returns true, you should call the ContextualMenuSelect function after generating your own menu and preparing an Apple Event descriptor (AEDesc) that describes the item for which your application is displaying a contextual menu. This descriptor may contain an object specifier or raw data and will be passed to all contextual menu plug-ins.

The system will add other items before displaying the contextual menu, and it will remove those items before returning, leaving the menu in its original state.

After all the system commands are added, the contextual menu is displayed and tracked. If the user selects one of the system items, it is handled by the system and the call returns as though the user didn't select anything from the menu. If the user selects any other item (or no item at all), the Menu Manager passes back appropriate values in the parameters outUserSelectionType, outMenuID, and outMenuItem.

Your application should provide visual feedback indicating the item that was clicked upon. For example, a click on an icon should highlight the icon, while a click on editable text should not eliminate the current selection.

If the outUserSelectionType parameter contains kCMMenuItemSelected, you should look at the outMenuID and outMenuItem parameters to determine what menu item the user chose and handle it appropriately. If the user selected kCMHelpItemSelected, you should open the proper Apple Guide sequence or other form of custom help.

SEE ALSO

"Contextual Menu Gestalt Selector Constants".